﻿<!--
    Mango - Open Source M2M - http://mango.serotoninsoftware.com
    Copyright (C) 2006-2011 Serotonin Software Technologies Inc.
    @author Matthew Lohbihler
    
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see http://www.gnu.org/licenses/.
 -->

<h1>Обзор</h1>
<p>Приемник HTTP используется для приема данных при помощи методов HTTP GET  или POST. Данные могут быть отправлены любым приложением, которое может работать как HTTP-клиент, наиболее очевидный пример – это веб-браузер, хотя существует много других приложений.</p>
<p>Можно настроить группу HTTP-приемников, каждый из которых будет прослушивать разные данные (например, идентификаторы устройств или IP-адреса).</p>
<p>Данные принимаются по адресу /httpds. Поэтому, если Ваша система доступна, например, по адресу 'http://localhost/', данные должны быть направлены по адресу 'http://localhost/httpds'. Попробуйте прямо <a href="httpds?testKey=testValue" target="_blank">сейчас</a>. Эта ссылка отправляет параметр с именем 'testKey' со значением 'testValue'. Скорее всего, ни один из приемников не ожидает параметр с таким именем, поэтому Вам придет сообщение 'Нераспознанный ключ: testKey'. Это нормально; такое сообщение подскажет пользователю, что данные отправлены, но не используются. </p>
<h1>Конфигурация</h1>
<p>Каждый источник данных должен иметь произвольно заданное Имя.</p>
<p>Белый список удаленных IP-адресов – это функция безопасности, которая выдает указание источнику данных игнорировать IP-адреса, не соответствующие заданным маскам IP-адресов. Более подробная информация о форматировании масок приводится ниже.</p>
<p>Белый список идентификаторов устройств обеспечивает дополнительный уровень безопасности, а также маршрутизацию данных. Он содержит описание устройств, которых прослушивает источник данных. Написание идентификаторов устройств не зависит от регистра. Кроме того, в конце идентификатора устройства можно добавлять знак '*'. Например, маска 'site10*' будет соответствовать устройствам с идентификатором 'site10', 'SITE10temp', 'site10HUM', и т.п. Идентификатор устройства указывается в HTTP-запросе с именем параметра __device (с двумя нижними прочерками). Информация по другим параметрам запросов приводится ниже в разделе Параметры запроса.</p>
<p>'Белые списки', или разрешающие списки, применяются чаще благодаря тому, что обеспечивают более надежную защиту, нежели 'черные списки', в которых вносятся запрещенные элементы. Чтобы добавить значение в белый список, введите его в соответствующем текстовом окне и нажмите сопровождающую его пиктограмму <img src="images/add.png"/>. Чтобы удалить значение, нажмите пиктограмму <img src="images/bullet_delete.png"/> рядом со значением. </p>
<h1>Маски IP-адресов</h1>
<p>'Маска' – это IP-адрес, который может содержать универсальные символы ('*') или числовые диапазоны. IP-адреса задаются при помощи формата IPv4, состоящего из четырех разделенных точкой значений, каждое из которых является числом от 0 до 255 (например, '192.168.0.10'). Каждая из четырех частей маски может быть либо конкретным числом, соответствие с которым должно быть полным, либо числовым диапазоном, заданным при помощи двух чисел, разделенных знаком '-'. Например, правильная маска записывается так: '192.168.10-15.*'. Эта запись означает, что первое число должно быть 192, второе – 168, третьим может быть любое число от 10 до 15 включительно, и четвертое может быть любым числом (от 0 до255). Маска по умолчанию '*.*.*.*' означает, что все IP-адреса доступны.</p>
<h1>Параметры запросов</h1>
<p>
  Запросы доставляются с помощью обычных параметризованных форматов HTML-запроса. При использовании метода GET, формат запроса выглядит так: 'http://&lt;domain name and port&gt;/&lt;optional path&gt;/httpds?param1=value1&amp;param2=value2'. Запросы, отправляемые при помощи метода POST, обычно требуют применения специализированного клиента. Если вы хотите использовать метод POST, обратитесь к документации клиента.</p>
<p>
  Значения объектов могут быть заданы двумя способами. Первый способ – при помощи формата 'pointName=pointValue' ('Имя точки = Значение точки). Второй – при помощи ключа и значения в виде двух раздельных параметров с префиксом-ключом '__Point'  and '__Value'. Например, выражение '__pointFoo=pointName&amp;__valueFoo=pointValue' (сопоставленные по значению 'Foo' после префикса) равнозначно выражению 'pointName=pointValue'.</p>
<p>Порядок, в котором располагаются параметры запроса, не имеет значения. Ниже приводятся специальные ключи параметров запросов. Обратите внимание, что все они начинаются с двух нижних прочерков. Все эти ключи являются необязательными.</p>
<p>
  Метки времени могут быть представлены различными способами. Если обнаружена метка времени (т.е. она не пустая), Mango будет пытаться обработать ее сначала в формате &quot;yyyyMMddHHmmss&quot; (&quot;ггггММддЧЧммсс&quot;), затем в формате &quot;yyyy-MM-dd'T'HH:mm:ss'Z'&quot; (&quot;гггг-MM-дд'T'ЧЧ:мм:сс'Z'&quot;), и наконец в количестве миллисекунд, прошедших с 00:00 1 января 1970 г. (Смотри раздел «Форматы даты/времени»). </p>
<ul>
  <li><b>__device</b> &ndash; идентификатор устройства отправителя</li>
  <li><b>__time</b> &ndash; замена времени</li>
  <li><b>__point</b> &ndash; префикс, который обеспечивает альтернативный способ передачи имени параметра. После префикса следует произвольный набор символов, который долджен быть единым с аналогичным полем после префикса  '__value'. Например, выражение '__pointFoo=pointName&amp;__valueFoo=pointValue' (сопоставленные по значению 'Foo' после префикса) равнозначно выражению 'pointName=pointValue'. Символы, указанные после префикса, используются только для установления соответствия, в остальном они не нужны.</li>
  <li><b>__value</b> &ndash; префикс, который выдает соответствующее значение ключа, заданного префиксом '__point'. </li>
</ul>

<h1>Проверка при помощи приемника HTTP </h1>
<p>Вы можете просмотреть данные, которые получает Ваша система, если нажмете на кнопку 'Принять данные HTTP'. Обратите внимание, что текущие параметры настройки белого списка будут использоваться в качестве фильтра запросов. Чтобы посмотреть все входящие данные, установите маску IP-адреса '*.*.*.*' и маску идентификатора устройства '*'.</p>
<p>После получения данных, все сведения отражаются в окне приемника. В первой строке содержится IP-адрес (который впоследствии можно будет использовать в белом списке IP-адресов). Вторая строка содержит идентификатор устройства или '(none)' («ничего»), если параметр отсутствует.</p>
<p>Третья строка показывает время запроса. По умолчанию устанавливается системное время, но его можно заменить параметром<strong> __time</strong> (время).</p>
<p>Оставшиеся строки данных содержат ключи отдельных параметров и значения, которые были получены, в формате 'key=value' ('ключ=значение').</p>
<p>Приемник будет прослушивать запросы до тех пор, пока не будет нажата кнопка «Отмена» или до перезагрузки системы.</p>
<h1>Примеры</h1>
<p>Для краткости опускаем доменные имена.</p>
<p>
  <b>httpds?__device=boilerA&amp;temp=215.5&amp;hum=77.4&amp;state=running</b> <br/>
  имеет тот же результат, что и <br/> <b>httpds?__device=boilerA&amp;__point1=temp&amp;__value1=215.5&amp;__pointFoo=hum&amp;__valueFoo=77.4&amp;__pointBar=state&amp;__valueBar=running</b>
</p>
<p>
  <b>httpds?presents=true&amp;__time=20071225073000</b>
</p>

<h1>HTTP-ответы </h1>
<p>
  На успешные запросы, направленные приемнику, выдается ответ '200 OK'. В случае, если в результате запроса возникает ошибка, в содержании HTTP-ответа будет выдаваться следующее сообщение об ошибке или предупреждение:</p>
<ul>
  <li>
    'Time override parse error' («ошибка обработки значения замены времени»), означающее, что значение замены времени было некорректно задано. Запрос будет принят с системным временем.</li>
  <li>
    'Unconsumed key' ('Нераспознанный ключ'), означающее, что заданный ключ параметра не используется ни одним объектом данных приемника HTTP. <br>
  </li>
  <li>
    'Value not found for paired point key' ('Не найдено значение для соответствующего ключа объекта'), означающее, что ключ параметра, указанный при помощи механизма '__point/__value' не подходит к значению. Параметр не будет включен в обработку запроса. </li>
</ul>
<p>По умолчанию только приведенные выше сообщения выдаются в ответ на HTTP-запрос. Если Вам нужны дополнительные сообщения в ответ на запросы, вы можете указать постоянную часть в качестве вступления (записывается перед сообщением об ошибке или предупреждением) или заключения (записывается после сообщения об ошибке или предупреждения). Чтобы установить пользовательский текст, используйте следующие выражения для вставки (или аналогичные выражения для обновления, если ключ уже существует):</p>
<pre>
  insert into systemSettings (settingName, settingValue) values ('httpdsPrologue', 'my prologue content')
  insert into systemSettings (settingName, settingValue) values ('httpdsEpilogue', 'my epilogue content')
</pre>